Developer Guide - Overview¶
Introduction¶
This Developer Guide documents how experienced developers can set their own challenges for either Python Beginners or Python Programming readers, such that the readers can use this framework to confirm that their code successfully completes the challenge.
Every challenge will require the user to implement a single function, which takes one or more inputs (either positional or keyword or both) and will return one or more values. As the person setting the challenge your role is the clearly described the requirements you expect the entrants to meet, and define a set of test data that is sufficient to show that the entrants code meets the requirments.
Required Contents¶
In order to provide a programming challenge under this framework you will need to provide
- description.rst - An English language description of the challenge; a clear definition of the functionality expected formatted in rST structure. The description should state any exceptions that the code should raise. See Description Guidelines for more information.
- testdata.json - A json file that defines the data sets which will be passed to the function in order to confirm that the function meets the description. See Test Data Guidelines for details on how to write this critical file. Note that errors in this file will be presented to the user during testing of their code, and those errors are likely to confuse challenge entrants.
- An examplar solution to the challenge - this is not published but is required to test your challenge information before publication.
Please read the documentation while developing this content.
Pre requisites¶
Apart from a good knowledge of Python, there is a short list of pre-requisites
- You are a known contributor to either Python Beginners or Python Programming spaces on Quora
- You have git on your developement machine
- you have an account on Git Hub - and are familiar with cloning, forking, branches and pull requests.
Process Overview¶
There is a simple 9 step process to provide your own challenges :
- Create a GIT fork of QuoraChallengesTestData and clone that fork to your local computer.
- Create a new developement branch in your local copy.
- Create a new folder at the top level of the repository - the name of folder is the chosen name for the challenge. The folder name must be in lowercase.
- Within the new folder create the following files description.rst, testdata.json and any optional files that your challenge requires.
- Edit the Readme.rst in the top level directory to add your challenge to the list.
- Write your exemplar solution, and test your solution and your testdata.
- Once all of the requirements are complete, commit and push the branch to your git hub repository. Do not commit your exemplar solution.
- Request a pull request to merge your branch into the main repository.
- Once the merge has been completed - publicise your challenge in the appropriate space.
To make it clear - these are the changes and new files that are required in order to create a new challenge :
File Changes required in the QuoraChallengesTestData repository.
Warning
Please do not publicise your challenge until the merge is complete. Until the merge completes, the testdata and description will not be available to the public.
Likely Audiences¶
When developing your challenge, please keep in mind at all times the target audience.
- The Python Beginners space is intended for those developers who are just starting out with Python and likely just starting out with development. It is likely that they wont be up to speed with most data structure and algorithms.
- Challenges aimed at the developers in Python Programming (who generally have skill level intermediate and beyond) will be much less common and the challenges should be open to multiple styles of solution, using data structures and algorithms
Key Additional Information¶
Make sure you are familiar with these additional guidelines in order to complete your challenge.